<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg">
  <head>
    <title>Application and Arguments Lists</title>
    <link rel="stylesheet" type="text/css" href="docbook-epub.css"/>
    <link rel="stylesheet" type="text/css" href="kawa.css"/>
    <script src="kawa-ebook.js" type="text/javascript"/>
    <meta name="generator" content="DocBook XSL-NS Stylesheets V1.79.1"/>
    <link rel="prev" href="Procedures.xhtml" title="Procedures"/>
    <link rel="next" href="Procedure-properties.xhtml" title="Procedure properties"/>
  </head>
  <body>
    <header/>
    <section class="sect1" title="Application and Arguments Lists" epub:type="subchapter" id="Application-and-Arguments-Lists">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both">Application and Arguments Lists</h2>
          </div>
        </div>
      </div>
      <p>When a procedure is called, the actual argument expression are evaluated,
and the resulting values becomes the actual argument list.
This is then matched against the formal parameter list
(in the procedure definition), and assuming they match,
the procedure body is called.
</p>
      <section class="sect2" title="Arguments lists" epub:type="division" id="idm139667877516224">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Arguments lists</h3>
            </div>
          </div>
        </div>
        <p>An argument list has three parts:
</p>
        <div class="itemizedlist" epub:type="list">
          <ul class="itemizedlist" style="list-style-type: disc; ">
            <li class="listitem" epub:type="list-item">
              <p>Zero or more <em class="firstterm">prefix arguments</em>, each of which is a value.
These typically get bound to named required or optional formal parameters,
but can also get bound to patterns.
</p>
            </li>
            <li class="listitem" epub:type="list-item">
              <p>Zero or more <em class="firstterm">keyword arguments</em>, each of which is a keyword
(an identifier specified with keyword syntax) combined with a value.
These are bound to either named keyword formal parameters, or
bundled in with a rest parameter.
</p>
            </li>
            <li class="listitem" epub:type="list-item">
              <p>Zero or more <em class="firstterm">postfix arguments</em>, each of which is a value.
These are usually bound to a “rest” formal parameter, which
receives any remaining arguments.
</p>
              <p>If there are no keyword arguments, then it ambiguous where
prefix arguments and and where postfix arguments start.
This is normally not a problem: the called procedure can
split them up however it wishes.
</p>
            </li>
          </ul>
        </div>
        <p>Note that all keyword arguments have to be grouped together:
It is not allowed to have a keyword argument followed by a plain
argument followed by a keyword argument.
</p>
        <p>The argument list is constructed by evaluating the each <a class="link" href="Primitive-expression-syntax.xhtml#meta-operand"><em class="replaceable"><code>operand</code></em></a>
of the <a class="link" href="Primitive-expression-syntax.xhtml#meta-procedure-call"><em class="replaceable"><code>procedure-call</code></em></a> in order:
</p>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><em class="replaceable"><code>expression</code></em>
</dt>
            <dd>
              <p>The <em class="replaceable"><code>expression</code></em> is evaluated, yielding a single value
that becomes a prefix or postfix argument.
</p>
            </dd>
            <dt class="term"><em class="replaceable"><code>keyword</code></em> <em class="replaceable"><code>expression</code></em>
</dt>
            <dd>
              <p>The <em class="replaceable"><code>expression</code></em> is evaluated.  The resulting value combined
with the <em class="replaceable"><code>keyword</code></em> becomes a keyword argument.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>@</strong></span></code><em class="replaceable"><code>expression</code></em>
</dt>
            <dd>
              <p>The <em class="replaceable"><code>expression</code></em> is evaluated.
The result must be a sequence - a list, vector, or primitive array.
The values of the sequence are appended to the resulting argument list.
Keyword arguments are not allowed.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>@:</strong></span></code><em class="replaceable"><code>expression</code></em>
</dt>
            <dd>
              <p>The <em class="replaceable"><code>expression</code></em> is evaluted.
The result can be a sequence;
a hash table (viewed as a collection of (keyword,value) pairs);
or an <em class="firstterm">explicit argument list</em> object, which is a sequence of values
<span class="emphasis"><em>or</em></span> keyword arguments.
The values and keyword arguments
are appended to the resulting argument list, though subject to the restriction
that keyword arguments must be adjacent in the resulting argument list.
</p>
            </dd>
          </dl>
        </div>
      </section>
      <section class="sect2" title="Explicit argument list objects" epub:type="division" id="idm139667877498112">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Explicit argument list objects</h3>
            </div>
          </div>
        </div>
        <p>Sometimes it is useful to create an argument list out of
pieces, take argument lists apart, iterate over them,
and generally treat an argument list as an actual first-class value.
</p>
        <p>Explicit argument list objects can take multiple forms.
The simplest is a sequence: a list, vector, or primitive array.
Each element of the list becomes a value in the resulting argument list.
</p>
        <pre class="screen">(define v1 '(a b c))
(define v2 (int[] 10 11 12 13))
(list "X" @v1 "Y" @v2 "Z")
  ⇒ ("X" a b c "Y" 10 11 12 13 "Z")
</pre>
        <p>Things get more complicated once keywords are involved.
An explicit argument list with keywords is only allowed
when using the <code class="literal">@:</code> splicing form,
not the <code class="literal">@</code> form.  It can be either
a hash table (anything the implement <code class="literal">java.util.Map</code>
or the types <code class="literal">arglist</code> or <code class="literal">argvector</code>.
</p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p><span class="emphasis"><em>Design note:</em></span> An argument list with keywords is straightforward
in Common Lisp and some Scheme implementations (including order versions of
Kawa): It’s just a list some of whose <code class="literal">car</code> cells are keyword objects.
The problem with this model is neither a human or the compiler can
reliably tell when an argument is a keyword, since any variable
might have been assigned a keyword.  This limits performance and
error checking.
</p>
          </blockquote>
        </div>
        <p>A hash table (anything the implement <code class="literal">java.util.Map</code>)
whose keys are strings or keyword objects is
interpreted as a sequence of keyword arguments,
using the hash-table keys and values.
</p>
        <p class="synopsis" kind="Type"><span class="kind">Type</span><span class="ignore">: </span><a id="idm139667877489872" class="indexterm"/> <code class="function">argvector</code></p>
        <p class="synopsis" kind="Constructor"><span class="kind">Constructor</span><span class="ignore">: </span><a id="idm139667877487456" class="indexterm"/> <code class="function">argvector</code> <em class="replaceable"><code><a class="link" href="Primitive-expression-syntax.xhtml#meta-operand"><em class="replaceable"><code>operand</code></em></a></code></em><em class="replaceable"><code><sup>*</sup></code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>List of arguments represented as an immutable vector.
A keyword argument takes two elements in this vector:
A keyword object, followed by the value.
</p>
            <pre class="screen">(define v1 (argvector 1 2 k1: 10 k2: 11 98 99))
(v1 4) ⇒ 'k2
(v1 5) ⇒ 11
</pre>
            <p>When <code class="literal">v1</code> is viewed as a vector it
is equivalent to <code class="literal">(vector 1 2 'k1: 10 'k2: 11 98 99)</code>.
(Note in this case the keywords need to be quoted, since
the <code class="literal">vector</code> constructor does not take keyword arguments.)
However, the <code class="literal">argvector</code> “knows” which arguments
are actually keyword arguments, and can be examined using the
<code class="literal">(kawa arglist)</code> library discussed below:
</p>
            <pre class="screen">(arglist-key-count (argvector 1 x: 2 3)) ⇒ 1
(arglist-key-count (argvector 1 'x: 2 3)) ⇒ 0
(arglist-key-count (vector 1 'x: 2 3)) ⇒ 0
</pre>
            <p>In this case:
</p>
            <pre class="screen">(fun 'a @:v1)
</pre>
            <p>is equivalent to:
</p>
            <pre class="screen">(fun 'a 1 2 k1: 10 k2: 11 98 99)
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Type"><span class="kind">Type</span><span class="ignore">: </span><a id="idm139667877477792" class="indexterm"/> <code class="function">arglist</code></p>
        <p class="synopsis" kind="Constructor"><span class="kind">Constructor</span><span class="ignore">: </span><a id="idm139667877475376" class="indexterm"/> <code class="function">arglist</code> <em class="replaceable"><code><a class="link" href="Primitive-expression-syntax.xhtml#meta-operand"><em class="replaceable"><code>operand</code></em></a></code></em><em class="replaceable"><code><sup>*</sup></code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Similar to <code class="literal">argvector</code>, but compatible with <code class="literal">list</code>.
If there are no keyword arguments, returns a plain list.
If there is at least one keyword argument creates a special
<code class="literal">gnu.mapping.ArgListPair</code> object that implements the
usual <code class="literal">list</code> properties but internally wraps a <code class="literal">argvector</code>.
</p>
          </blockquote>
        </div>
      </section>
      <section class="sect2" title="Argument list library" epub:type="division" id="idm139667877468752">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Argument list library</h3>
            </div>
          </div>
        </div>
        <pre class="screen">(import (kawa arglist))
</pre>
        <p>In the following, <em class="replaceable"><code>args</code></em> is an <code class="literal">arglist</code> or <code class="literal">argvector</code>
(or in general any object that implement <code class="literal">gnu.mapping.ArgList</code>).
Also, <em class="replaceable"><code>args</code></em> can be a generalized list, in which case it
behaves like an <code class="literal">argvector</code> that has no keyword arguments.
</p>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667877464048" class="indexterm"/> <code class="function">arglist-walk</code> <em class="replaceable"><code>args</code></em> <em class="replaceable"><code>proc</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Call <em class="replaceable"><code>proc</code></em> once, in order, for each argument in <em class="replaceable"><code>args</code></em>.
The <em class="replaceable"><code>proc</code></em> is called with two arguments,
corresponding to <code class="literal">(arglist-key-ref <em class="replaceable"><code>args</code></em> <em class="replaceable"><code>i</code></em>)</code>
and <code class="literal">(arglist-arg-ref <em class="replaceable"><code>args</code></em> <em class="replaceable"><code>i</code></em>)</code> for each <em class="replaceable"><code>i</code></em> from 0
up to <code class="literal">(arglist-arg-count <em class="replaceable"><code>args</code></em>)</code> (exclusive).
I.e. the first argument is either <code class="literal">#!null</code> or the keyword (as a string);
the second argument is the corresponding argument value.
</p>
            <pre class="screen">(define (print-arguments args #!optional (out (current-output-port)))
  (arglist-walk args
                (lambda (key value)
                  (if key (format out "key: ~a value: ~w~%" key value)
                      (format out "value: ~w~%" value)))))
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667877453792" class="indexterm"/> <code class="function">arglist-key-count</code> <em class="replaceable"><code>args</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Return the number of keyword arguments.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667877450384" class="indexterm"/> <code class="function">arglist-key-start</code> <em class="replaceable"><code>args</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Number of prefix arguments, which is the number of arguments before
the first keyword argument.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667877446928" class="indexterm"/> <code class="function">arglist-arg-count</code> <em class="replaceable"><code>args</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Return the number of non-keyword arguments.
(The count includes neither the keywords nor the corresponding values.)
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667877443456" class="indexterm"/> <code class="function">arglist-arg-ref</code> <em class="replaceable"><code>args</code></em> <em class="replaceable"><code>index</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Get the <em class="replaceable"><code>index</code></em>’th argument value.
The <em class="replaceable"><code>index</code></em> counts keyword argument values, but not the keywords themselves.
</p>
            <pre class="screen">(arglist-arg-ref (arglist 10 11 k1: -1 19) 2) ⇒ -1
(arglist-arg-ref (arglist 10 11 k1: -1 19) 3) ⇒ 19
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667877438208" class="indexterm"/> <code class="function">arglist-key-ref</code> <em class="replaceable"><code>args</code></em> <em class="replaceable"><code>index</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>The <em class="replaceable"><code>index</code></em> counts arguments like <code class="literal">arglist-arg-ref</code> does.
If this is a keyword argument, return the corresponding keyword
(as a string); otherwise, return <code class="literal">#!null</code> (which counts are false).
</p>
            <pre class="screen">(arglist-key-ref (argvector 10 11 k1: -1 k2: -2 19) 3) ⇒ "k2"
(arglist-key-ref (argvector 10 11 k1: -1 k2: -2 19) 4) ⇒ #!null
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667877432336" class="indexterm"/> <code class="function">arglist-key-index</code> <em class="replaceable"><code>args</code></em> <em class="replaceable"><code>key</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Search for a keyword matching <em class="replaceable"><code>key</code></em> (which must be an interned string).
If there is no such keyword, return -1.
Otherwise return the keyword’s index as as argument to <code class="literal">arglist-key-ref</code>.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667877427520" class="indexterm"/> <code class="function">arglist-key-value</code> <em class="replaceable"><code>args</code></em> <em class="replaceable"><code>key</code></em> <em class="replaceable"><code>default</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Search for a keyword matching <em class="replaceable"><code>key</code></em> (which must be an interned string).
If there is no such keyword, return the <em class="replaceable"><code>default</code></em>.
Otherwise return the corresponding keyword argument’s value.
</p>
          </blockquote>
        </div>
      </section>
      <section class="sect2" title="Apply procedures" epub:type="division" id="idm139667877422304">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Apply procedures</h3>
            </div>
          </div>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667877421232" class="indexterm"/> <code class="function">apply</code> <em class="replaceable"><code>proc</code></em> <em class="replaceable"><code>argi</code></em><em class="replaceable"><code><sup>*</sup></code></em> <em class="replaceable"><code>argrest</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p><em class="replaceable"><code>Argrest</code></em> must be a sequence (list, vector, or string) or a
primitive Java array.
(This is an extension over standard Scheme, which requires that
<em class="replaceable"><code>args</code></em> be a list.)
Calls the <em class="replaceable"><code>proc</code></em> (which must be a procedure), using as arguments
the <em class="replaceable"><code>argi</code></em>... values plus all the elements of <em class="replaceable"><code>argrest</code></em>.
</p>
            <p>Equivalent to: <code class="literal">(</code><em class="replaceable"><code>proc</code></em> <em class="replaceable"><code>argi</code></em><sup>*</sup> <code class="literal">@</code><em class="replaceable"><code>argrest</code></em><code class="literal">)</code>.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Syntax"><span class="kind">Syntax</span><span class="ignore">: </span><a id="idm139667877411728" class="indexterm"/> <code class="function">constant-fold</code> <em class="replaceable"><code>proc</code></em> <em class="replaceable"><code>arg1</code></em> <em class="replaceable"><code>...</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Same as <code class="literal">(<em class="replaceable"><code>proc</code></em> <em class="replaceable"><code>arg1</code></em> ...)</code>, unless <em class="replaceable"><code>proc</code></em> and
all the following arguments are compile-time constants.
(That is:  They are either constant, or symbols that have a global
binding and no lexical binding.)  In that case, <em class="replaceable"><code>proc</code></em>
is applied to the arguments at compile-time, and the result replaces
the <code class="literal">constant-fold</code> form.  If the application raises an exception,
a compile-time error is reported.
For example:
</p>
            <pre class="screen">(constant-fold vector 'a 'b 'c)
</pre>
            <p>is equivalent to <code class="literal">(quote #(a b c))</code>, assuming <code class="literal">vector</code>
has not been re-bound.
</p>
          </blockquote>
        </div>
      </section>
    </section>
    <footer>
      <div class="navfooter">
        <ul>
          <li>
            <b class="toc">
              <a href="Application-and-Arguments-Lists.xhtml#idm139667877516224">Arguments lists</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Application-and-Arguments-Lists.xhtml#idm139667877498112">Explicit argument list objects</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Application-and-Arguments-Lists.xhtml#idm139667877468752">Argument list library</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Application-and-Arguments-Lists.xhtml#idm139667877422304">Apply procedures</a>
            </b>
          </li>
        </ul>
        <p>
          Up: <a accesskey="u" href="Procedures.xhtml">Procedures</a></p>
        <p>
        Next: <a accesskey="n" href="Procedure-properties.xhtml">Procedure properties</a></p>
      </div>
    </footer>
  </body>
</html>
